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ABSTRACT 

We present a suite of IDL routines to interactively run GalFit whereby the various surface brightness 
profiles (and their associated parameters) are represented by regions, which the User is expected to 
place. The regions may be saved and/or loaded from the ASCII format used by ds9 or in the 
Hierarchical Data Format (version 5). The software has been tested to run stably on Mac OS X and 
Linux with IDL 7.0.4. In addition to its primary purpose of modeling galaxy images with GalFit, this 
package has several ancillary uses, including a flexible image display routines, several basic photometry 
functions, and qualitatively assessing SExtractor. We distribute the package freely and without any 
implicit or explicit warranties, guarantees, or assurance of any kind. We kindly ask users to report 
any bugs, errors, or suggestions to us directly (as opposed to fixing them themselves) to ensure version 
control and uniformity. 



Subject headings: methods: data analysis — techniques: image processing 
galaxies: fundamental parameters 



galaxies: structure 
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1. INTRODUCTION 

The shape, size, and structure of distant galaxies can 
provide invaluable insight to their formation history. 
Consequently, many there have been many techniques 
and codes d eveloped to make these measurements: GIM2D 
(iMarleau fc Simard 1998), GalFit ( Peng et al. 2002, 
I2010f l. GASPHOT (PignateUi. Fa sano. fc Cassatal 120061 ). 
and GALPHAT (Yoon. Weinber g, fc Kat j 1201 Ih . While 
this is in no way meant to be an exhaustive list, it merely 
highlights the interest in, and emphasis placed on, ro- 
bustly measuring the properties of the two-dimensional 
light distributions of galaxies. 

As astronomical surveys have grown ever wider, sam- 
ples of galaxies have become larger, and accordingly these 
detailed modeling techniques have also evolved. Turn- 
ing toward a "pipeline approach," whereby many so- 
phisticated programs are called in concert to stream- 
line the measuremen ts on large samples (e.g. GALAPAGOS. 
IHaufiler. et alllMTh . many authors sacrifice detailed fit- 
ting for bulk properties. Naturally, such a paradigm will 
invariably generate a series of tunable parameters to be 
set by the User, many of which, can significantly alter 
the success or reliability of the pipeline. While appro- 
priate settings are likely obvious or easily ascertained, 
they are often tailored to a particular sample, and as 
the sample changes so must the settings. For example. 
Users often need to provide the shape modeling codes a 
source list, since rarely do these codes also identify ob- 
jects. Obviously, this places the utmost importance on 
the identification scheme, for multiple reasons: First and 
most obviously, if the object of interest is failed to be 
cataloged, then clearly the power of the pipeline is for 
not. Secondly, if the identification software fails to "de- 
blend" a neighboring object, which presumably should 
be either simultaneously modeled or masked from the 
fitting, then the results are not to be trusted. Both 



|rryan@stsci.edu 

Physics Department, University of California, Davis, CA 
95616 

Space Telescope Science Institute, Baltimore, MD 21218 



of these issues (and many others) can be mitigated by 
human-intervention or supervision throughout the pro- 
cess, which is the primary motivation for this work. 

In this article, we present our software, iGalFit, which 
is a graphical user interface (GUI) for running GalFit. 
The software is inspired by the successful image dis- 
play tool, ds^ (and its predecessors), produced and 
maintained by the Chandra X-ray Science Center. In 
iGalFit, the Users is expected to place (circular, ellip- 
tical, and rectangular) regions on the image to indicate 
the function to be fit and the initial guesses of the pa- 
rameters. In this way, the User has complete control 
over the critical identification step, while abdicating the 
assembly-line power of a pipeline. 

This article should be treated as somewhat of a "User's 
Manual" and a reference point for the package. The ar- 
ticle is organized as follows: in Section [5] we describe 
the basics of the code, in Section [3] we briefly describe a 
second package to integrate SExtractor with GalFit, in 
Section [4] we discuss potential ancillary uses, and in Sec- 
tion [5] we mention several upgrades for future versions. 

2. INTERACTIVE GalFit: iGalFit 

2.1. Installing iGalFit 

The entire package is written in the Interactive Data 
Language^ (hereafter IDL), therefore having IDL in- 
stalled is an obvious prerequisite. With IDL installed, 
the installation is relatively straightforward: 

1. Obtain the IDL routines for _iGalFit from 
[littp://dls.physics.ucdavis.edu/~rer/| or by email- 
ing the author. 

2. Create an environment variable in your start-up file 
named igalf it, and set it equal to the full-path of 
the IDL routines. 

^ http:/ /hea-www. harvard.edu/RD/ds9/ 

* http : / / www.itt vis . com /language / en- 

us / productsservices /idl. aspx 
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TABLE 1 





iGalFi 


T Optional Inputs 


IDLT 


Perl 


Function 


LOADSETTINGS 


-load 


Load an iGalFit save file. 


SCIFILE 


-sci 


Load the science image. 


UNCFILE 


-unc 


Load the uncertainty image. 


PSFFILE 


-psf 


Load the PSF image. 


BPXFILE 


-bpx 


Load the bad-pixel image. 


IMGFILE 


-img 


Load the output image. 


MAGZERO 


-zero 


Set the magnitude zcropoint. 


t While IDL is not case- 


sensitive, we follow the convention that 


optional keywords 


are in 


all-caps. 



3. Amend the IDL_PATH variable to include this newly 
set variable. Obviously, the variable should be set 
ABOVE the IDL_PAfH setting. 



4. For the Mac OS X platform, configure the "Ap- 
ple Key" for the keyboard accelerators used by 
iGalFit: 

(a) In the User's home directory, there may be a 
file called .Xdmodmap (if not, create one) and 
add the following lines: 

• clear modi 

• clear mod2 

• add modi = Meta_L 

(b) Start the XI 1 server and open the Preferences 
tab. Under the Input dialog, make the the 
following items are UNCHECKED: 

• Follow system keyboard layout 

• Enable key equivalents under XI 1 

5. To install the optional Perl script which can call 
iGalFit from the command line, simply include 
the path to the Perl executable in your start-up 
file. 

6. Restart the Xll server. 

2.2. Starting iGalFit 

Since the code is primarily written in IDL, the simplest 
way to start iGalFitis to issue the command "igalfit" at 
the IDL prompt: 

IDL> igalfit, [OPTIONS=options] 

This of course requires that IDL is running, which can 
be a nuisance. Therefore we include a brief Perl script, 
which will initialize IDL and run iGalFit and can be 
run from the command-line in the usual way. There are 
several optional keywords, which can be set in either the 
IDL or Perl, to (pre-)set various items. A complete list- 
ing can be given by typing "igalfit, /help" in IDL, "igalfit 
-help" at the command line, or are given in Table [H 



2.3. Controls 

The controls to iGalFit are largely modeled after 
those of ds9, and so users should be able to seamlessly 
move between programs. However, we will describe the 
control system for completeness: 



TABLE 2 
iGalFit Keyboard Commands 



Key Function 
-|- Zoom in on the center of the display. 

— Zoom out on the center of the display, 

q Close iGalFit. 

Delete Delete the selected region. 

r Display a radial profile of object closest to cursor position, 

m Display image statistics for a small area around the cursor 

position. 

1 Display a line plot for some region around the cursor posi- 

tion. 

c Display a column plot for some region around the cursor 

position. 

h Display a pixel histogram for some region around the cursor 

position. 

e Display a contour plot for some region around the cursor 

position. 



File Input /Output:: While many of the individual 
files needed to run GalFit can be saved/loaded at 
any time, users may find it convenient to save/load 
a file which encodes the complete state of iGalFit. 
This facilitates an easy recall or programmatically 
assigning a state of iGalFit. These files are writ- 
ten in the Hierarchical Data Format version 5 
(HDF5), though by default named igalfit_save.h5. 
These files can be saved/loaded by buttons on the 
toolbar or the File pulldown menu, or with the 
command line options (see Table [ij. 

Region Input/Output:: The regions for iGalFit in- 
dicate the positions, sizes, and morphologies of the 
objects to be fit, regions to be masked, and al- 
lowable fitting regions (discussed in more detail in 
§ 12.41 Users can save/load regions from the Re- 
gions pulldown menu, and are meant to be directly 
compatible with ds9. 

Mouse Functions:: The mouse controls many aspects 
of iGalFit: 

Left click and drag:: If on a blank region of the 
image, then a new region based on the current 
state of the morphology pulldown menu in the 
primary toolbar (see Figure [IJ . If on a valid 
region, then this will select the region allowing 
the user to translate or delete the region and 
initiate the region "handles." The handles can 
be selected to adjust the size (left click) and 
rotate (left click while holding the SHIFT key) . 

Middle click:: Recenter on the current mouse po- 
sition. 

Right click and drag:: Adjust the "stretch" of 
the color map — vertical and horizontal move- 
ments adjust the bias and contrast, respec- 
tively. 

Left double-click:: If on a region, then the Re- 
gion Information sub-GUI will open. 

Keyboard Commands:: When the cursor is in the 
main display window there are several actions 
which can be run by keyboard actions. We briefly 
describe the valid functions in Table [2j 



iGalFit User's Manual 



ooo 



iCalFit vl.O 



File DispUy Sc^le Zoom Regions 



Sci: 
Urc; 
PSF: 



p:r 



■d:r 



File I/o] Constraints] Ranges] Image Pr-op + 1 Ska] fldd.l 
File Input/Output 



E) Output Image 

F) Bad Pixel Mask 



Inspect 



r Make BPX 



^_HJ_^ S^rsic ^1 ^^2<J S| B| a| A| GalFil| SEX 




Fig. 1. — Screenshot of iGalFit. We show iGalFit in its initial state: no image, regions, or sub-GUIs present. As discussed in ij 12.21 
many of the fields can be set programmatically from the IDL prompt or the command-line via our Perl script. 



Toolbar Functions:: Immediately above the main dis- 
play window is a row of buttons which control sev- 
eral commonly used functions (see Figure [T]) . We 
briefly describe the function of each button in Ta- 
ble El 



In principle, iGalFit is capable of displaying large 
(roughly 10 kx 10 k pixels). However, manipulating 
a large number of pixels is computationally expen- 
sive and is generally unnecessary (or ill-advised) 
for running GalFit. Therefore, we recommend op- 
erating on images sized for each object (roughly 
1 kx 1 k pixels). 



2.4. Modeling Galaxy Profiles 

The primary motivation for developing iGalFit was to 
interactively create the input files for GalFit (e.g. bad- 
pixel masks, constraint files, galfit.feedme" , and uncer- 
tainty maps). In this section, we describe the typical 
order-of-operations to interactively model galaxy pro- 
files. 



While GalFit is capable of running without a PSF 
and uncertainty map, these images are essential for 
robust estimates of the galaxy profiles. Further- 
more, GalFit is more reliable when operating on 
images which are in the units of counts (cts; Peng 
priv. comm.), despite the more common convention 
to process images in count rate (cts/s). Therefore 
the user should set the appropriate exposure time 
and unit in the Image Properties tab. Finally, for 



4 



Ryan Jr. 



TABLE 3 
iGalFit Toolbar 



Icon 



Function 



y 



X 

1^ 



GalFil 



Load an iGalFit save file. 
Save an iGalFit save file. 
Inspect an iGalFit save file. 
Zoom in on center of windovf. 
Zoom out on center of window. 
Delete currently selected region. 

View pixel histogram and set pixel min/max for display. 

View a pixel values under cursor (the size of the table can 
be set in the Preferences menu. 

Manually adjust the display settings (minimum, maximum, 
bias, and contrast). 

Manually edit the GalFit input file. 

Inspect and modify the properties of the loaded regions. 
Run GalFit with the current state. 
Launch the SExtractor sub-GUI. 



TABLE 4 
iGalFit Regions 



Shape 


Color 


Rotate 


Purpose 


ellipse 


green 


Y 


Fit Sersic function 




blue 


Y 


Fit ExpDisk function 




red 


Y 


Fit DeVauc function 




skyblue 


Y 


Fit Nuker function 




cyan 


Y 


Fit Edge-on Disk function 




seagreen 


Y 


Fit King function 




orange 


Y 


Fit Gaussian function 




maroon 


Y 


Fit Moffat function 




black 


Y 


Mask section 


circle 


magenta 


N 


Fit emprical PSF 




black 


N 


Mask section 


rectangle 


yellow 


N 


Define a fitting section 




black 


Y 


Mask section 



a meaningftil estimate of the and parameter un- 
certainties, the uncertainty image should represent 
all sources of uncertainty. Often t imes, particularly 
with data from MultiDrizzle (|Koekemoer et all 
[2002 ). the weight /uncertainty maps do not include 
any shot noise from the objects. If this is the case, 
then the user should set this flag and iGalFit will 
modify the uncertainty image according to 



U. 



\s, 



(1) 



where Sij is the science image — both the science 
and uncertainty images have units of counts. 

After loading a science image (and PSF and uncer- 
tainty maps), the user is expected to indicate the 
initial conditions for GalFit by drawing regions, 
which represent the model that should be fit. In 
Table |4j we list the currently supported regions and 
their functions. There are three ways a user may 
draw regions in iGalFit: 



Manual:: The primary advantage of iGalFit is 
the ability to interactively place the model 
profiles. In this way, the fitting can be done 



iteratively by modifying properties of the re- 
gions, such as the color (see Table|4]), position, 
adding/removing additional regions, or mask- 
ing objects. 

Automated:: Despite the obvious advantages 
with interactively placing regions, this can be 
very tedious and daunting for large images 
with many objects. Therefore, we include a 
second package which will call SExtractor to 
identify objects and draw the appropriate re- 
gions (discussed in more detail in § |^ ■ To de- 
termine which fitting function to assume (see 
Table SJ, we have a crude star/galaxy separa- 
tion algorithm of: 



ISDAREA. IMAGE < A„it 

R > i?crit 

ISOAREA. IMAGE < Acnt 

R < ^crit 



PSF 



Mask 



(2) 



(3) 



where we define R = V irah and (a, h) are 
the semi- (major, minor) axes, respectively. 
We consider objects which are considerably 
smaller in area and extent than the PSF to 
be likely image defects or unrejected cosmic 
rays, and in which case, should be masked in 
the GalFit calculations. All remaining ob- 
jects are considered to be extended, and are 
assigned a single fitting function. The tunable 
parameters (Acrit, -Rcrit) and default extended 
source function can be set in the Preferences 
menu in iGalFit. We caution that these clas- 
sifications are only meant to guide the user in 
placing the regions, and should not be trusted 
as a robust morphological indicator. 

File:: Regions can be loaded from a standard ds9 
regions file. In Appendix |X1 we give an exam- 
ple regions file to illustrate the format. 

3. With the fitting regions indicating the initial condi- 
tions of GalFit set, the user should consider setting 
two ancillary regions. First, any pixel which is seri- 
ously corrupted by non-object flus0 (such as cosmic 
rays, image defects, diffraction spikes, bleeds, etc.) 
should be masked. If bad pixels are left unmasked, 
then they will bias the estimate of the sky bright- 
ness by GalFit, which will adversely affect other 
parameters (notably the radius) and/or give incor- 
rect results for the objects directly (such as posi- 
tion, total magnitude, or radius). Second, users 
should consider setting a Fitting Section region, 
which restricts the GalFit calculation to the in- 
terior pixels. If the fitting section is not set, then 
iGalFit will fit the entire image. 

4. Once the fitting regions have been placed, the user 
should consider defining any possible constraints. 
While the use of constraints are discouraged, they 
do have some utility — particularly when fitting 



^ The sky pixels will be modeled by the , 
fore should not be masked. 



function, and there- 
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composite functions (such as bulge and disk). Ob- 
viously, any parameter which is found by GalFit 
to be fixed on a constraint border is dubious, and 
the user should relax the constraint. In most cases, 
if a constraint can be avoided, it is safest to do so. 

5. At any point in the process, the user can inspect the 
GalFit input file (e.g. galfit.feedme) and make any 
manual modifications. We caution, there are no 
safe-guards to verify that these files do not contain 
any errors. 

6. If GalFit successfully runs to completion, the de- 
fault behavior is to load the output file (e.g. img- 
block.fits) into a sub-GUI to display the results (see 
Figure [3]). This sub-GUI wiU display the science, 
model, and residual images (on the same stretch), 
the best-fit results, and global properties (e.g. de- 
grees of freedom, x^i sky properties, etc.). The 
various output images can also be displayed in the 
main GUI. 

3. SOURCE EXTRACTOR 

Since GalFit does not identify objects, the user is re- 
quired to indicate approximate positions of all sources, 
whether to be fit or masked. In many deep galaxy im- 
ages, the number of objects may be overwhelming to 
mark every source. Therefore, we include a separate 
GUI to run So urce Extractor (hereafter SExtractor; 
iBertin fc Arno uts 1996). While this package can be run 
independently of iGalFit, the main features are only 
accessible through iGalFit. There are a multitude of 
parameters which govern the operations, however we re- 
strict control to only the few which are most commonly 
modified. 

The SExtractor GUI employs two sub-GUIs to set the 
measurements (i.e. the *.param file) and build a convolu- 
tion filter (i.e. the *.conv files). The parameters needed 
for iGalFit are set by default. The convolution routine 
allows for several common filters (Gaussian, Mexican hat, 
top hat, delta- function) and a user-defined function of a 
single parameter. As of the time preparing this doc- 
ument, SExtractor (version 2.5.0 2009-09-30) did not 
permit any filters larger than 32 pixels, however iSEx 
will not warn the use of this potential issue. 

4. ANCILLARY USES 

While the primary purpose of iGalFit is to model the 
two-dimensional light distributions of various objects, we 
suggest other applications which users may find valuable. 

4.1. Interactively Assessing SExtractor Settings 

SExtractor has become the de facto standard for de- 
tecting and measuring a number of properties of faint 
objects, particularly for deep-field surveys. Not sur- 
prisingly, there are a host of tunable parameters to be 
set by the user which govern the detection, deblending, 
measurement, memory usage, and outputting. There- 
fore a typical session involving SExtractor begins with 
a trial-and-error period of tweaking various parameters 
until the output catalog satisfies some qualitative prop- 
erty, often times the detection/deblending of the faintest 
sources. Despite the various manuals (Source Extractor 
for Dummies: B. Holwerda, SExtractor User's Manual: 



OOG 1x1 SExtractor 

FilelHH^I^^^I^I^^^^^^^P' Help 

Background ] Check Images ] Hemcr-y ] Miscellaneous 
Inputs ^ Catalog ] Extraction ] Photometry 
Primary Inputs 

measurement image li 



measurement weight 
detection image 
detection weight 




Configuration File "sex.config 




I 



SEx executable j^sex Run SExtractor | j 
A 



Fig. 2. — A screenshot of the SExtractor GUL Each stanza of 
the default configuration file is represented as a separate tab. Ad- 
ditional sub-GUIs are included to create convolution filters (i.e. the 
*.conv files) and select parameters to be measured (i.e. the *.param 
files). While this GUI can be run independently of iGalFit, 
it is most useful when used in conjunction with iGalFit. The 
SExtractor GUI initializes with the parameters necessary to inter- 
face with iGalFit, and the user is discouraged from changing the 
CATALOG_TYPE or removing any measurement parameters (though 
adding parameters is acceptable). 

E. Bertin), there can be a great deal of confusion on the 
role of a given parameter and how it can be affected by 
other parameters, particularly for novice users. Since 
iGalFit can directly control SExtractor using a sep- 
arate interface, users are able to experiment with any 
combination of SExtractor settings and their effects. 

4.2. Inspect Images 

Since the controls and image display aspects of 
iGalFit was inspired by ds9, it has a many fiexible 
quick-look tools built-in. The images can be scaled 
and stretched, zoomed, panned, and separate frames (al- 
though this would be implemented by loading additional 
images into the PSF and Uncertainty fields) for easy dis- 
play and comparisons. At present, rotations are not sup- 
ported, but this will likely be included in subsequent ver- 
sions. As mentioned in § 12.41 the display and processing 
of large images ( 10k xlOk pixels) is ill-advised. 

4.3. Quick-Look Photometry 

One question that invariably arises in nearly all forms 
of observational astronomy: What is the brightness 
of that object? Therefore many astronomical display 
routines give the user tools to answer this question 
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Fig. 3. — Screenshot of the GUI to inspect the GalFit results. All of the information displayed here is taken from the GalFit output file 
(i.e. the imgblock.fits). This GUI has many of the same controls and mouse functionality as iGalFit. 



(e.g. ImExamine in IRAF, atv.prc0, idp3.prcCI iStobid 
I2006f l. and iGalFit is no different. However a major 
advantage to iGalFit is the photometry routines are in- 
tegrated into an image display tool which combines the 
flexibility of ds9 with the computational power of IDL 
and the image processing of SExtractor. 

5. FUTURE IMPROVEMENTS 

As with most software, iGalFit is a work-in-progress, 
and there are several additions or improvements we 
would like to include: 

Asymmetry Parameters:: In the latest version of 

® http: / /www. physics . uci.edu / ~barth / atv / 
http://mips.as.arizona.edu/MIPS/IDP3 



GalFit, there are a bevy of asymmetry parameters 
(e.g. boxiness, bending modes, fourier components, 
truncation radii) to model azimuthally asymmetric 
structures, like bars, spiral arms, or tidal tails. By 
including these parameters, the user can create far 
more complex and (perhaps) realistic models. 

Additional Morphological Programs:: While this 
project was conceived to provide a user-friendly 
interface to GalFit, there are additional modeling 

programs which can be included as we ll, for 

example GALPHAT ijYoon. Weinberg, fc K£itgi201lD 
shapelet decompositions (e.g. iRefregieiT 120031 : 
iMassev fc Refres|ig r"2005l. and model-independent 
estimators (e.g. IConsclice et al.. ,2003; ,Lotz et al] 
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[200llLaw et alJ[2007l) . 

Improved Memory Efficiency and Image Display:: 

We mentioned in § I2.4i the rendering of large 
images can be very computationally expensive and 
dramatically slow down even the most powerful 
workstations. In future versions, we plan to 
employ additional advanced graphics capabilities 
in IDL to improve the real-time image display. 
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APPENDIX 

A. EXAMPLE REGIONS FILE 

iGalFit will read and write regions files in the same format as ds9, allowing users to employ existing tasks to define 
regions. For completeness, we give an example regions file, as written by iGalFit. 

# Region file made by iGalFit on Men Aug 1 00:31:43 2011 

# Filename: psf _f 125w. f its 

global color=green dashlist=8 3 width=l f ont="helvetica 10 normal" select=l higlilite=l daslL=0 

fixed=0 edit=l move=l delete=l include=l source=l 
image 

circle (593, 586, 44. 019807) # color=magenta 
ellipse (456, 543, 75, 28, 338. 58853) # color=green 
ellipse(679,458,40,20,35.134193) # color=red 
ellipse(528,476,40,20,330.01836) # color=blue 
box(587.5,547.5,369,313,0) # color=yellow 
-box(537.5,605.5,37,59,0) # color=black 
-box(713,607,80,40,0) # color=black 

B. BASIC SExTRACTOR CATALOG 

As discussed in §|31 iGalFit can call SExtractor to identify objects for later use, but can also take a catalog derived 
by other means. However to properly interpret the columns, the file should be in the ASC11_HEAD format, here we give 
an example of a catalog which contains the mandatory fields (additional columns may be present). 



# 1 NUMBER Running object number 

# 2 1S0AREA_1MAGE Isophotal area above Analysis threshold [pixel**2] 

# 3 X_1MAGE Object position along x [pixel] 

# 4 Y_1MAGE Object position along y [pixel] 

# 5 MAG_AUTO Kron-like elliptical aperture magnitude [mag] 

# 6 MAGERR_AUTO RMS error for AUTO magnitude [mag] 

# 7 A_1MAGE Profile RMS along major axis [pixel] 

# 8 B_1MAGE Profile RMS along minor axis [pixel] 

# 9 THETA_1MAGE Position angle (CCW/x) [deg] 

# 10 FLAGS Extraction flags 
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17 


55, 


.004 


12, 


,177 


-8, 


.3319 


0, 


,0490 


1, 


,120 


0, 


,930 


-21, 


.7 





2 


118 


46, 


.653 


48, 


,326 


-10, 


.8804 


0, 


,0100 


2, 


,262 


2, 


,078 


-17, 


.9 
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22, 


.492 


47, 


,101 


-7, 


.7120 


0, 


,0458 


0, 


,594 


0. 


,569 


35, 


.4 






